---
title: 'Read replicas'
metaTitle: 'Read replicas'
metaDescription: 'Learn how to set up and use read replicas with Prisma Client'
tocDepth: 3
---

Read replicas enable you to distribute workloads across database replicas for high-traffic workloads. The [read replicas extension](https://github.com/prisma/extension-read-replicas), `@prisma/extension-read-replicas`, adds support for read-only database replicas to Prisma Client.

The read replicas extension supports Prisma ORM versions [5.2.0](https://github.com/prisma/prisma/releases/tag/5.2.0) and higher. For Prisma 7.0+, the extension requires passing full PrismaClient instances instead of connection URLs. If you run into a bug or have feedback, create a GitHub issue [here](https://github.com/prisma/extension-read-replicas/issues/new).


## Setup the read replicas extension

Install the extension:

```terminal
npm install @prisma/extension-read-replicas@latest
```

:::note[Prisma 7 compatibility]

The latest version of `@prisma/extension-read-replicas` requires **Prisma 7.0+** and uses a new API that requires passing full `PrismaClient` instances instead of connection URLs. This change is necessary due to Prisma 7's architectural changes.

If you're using Prisma 6.x or earlier, see the note below.

:::

Initialize the extension by extending your Prisma Client instance and provide the extension with full `PrismaClient` instances for your read replicas. The default approach is to use driver adapters:

```ts
import { readReplicas } from '@prisma/extension-read-replicas'
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from './generated/prisma/client'

// Create main client with adapter
const mainAdapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL!,
})

const mainClient = new PrismaClient({ adapter: mainAdapter })

// Create replica client with adapter
const replicaAdapter = new PrismaPg({
  connectionString: process.env.REPLICA_URL!,
})

const replicaClient = new PrismaClient({ adapter: replicaAdapter })

// Extend main client with read replicas
const prisma = mainClient.$extends(
  readReplicas({ replicas: [replicaClient] })
)

// Query is run against the database replica
await prisma.post.findMany()

// Query is run against the primary database
await prisma.post.create({ 
  data: {/** */},
})
```

:::note[For Prisma v6 users]

For Prisma v6 users, install version `0.4.1` of the Read Replicas extension:

```bash
npm install @prisma/extension-read-replicas@0.4.1
```

After installing, configure your replica like this:

```ts
import { PrismaClient } from '../prisma/generated/client'
import { readReplicas } from '@prisma/extension-read-replicas'

const prisma = new PrismaClient().$extends(
  readReplicas({
    url: process.env.DATABASE_URL_REPLICA,
  })
)

// This query runs against the read replica
await prisma.post.findMany()

// This query runs against the primary database
await prisma.post.create({
  data: { /* ... */ },
})
```

:::

All read operations, e.g. `findMany`, will be executed against the database replica with the above setup. All write operations — e.g. `create`, `update` — and `$transaction` queries, will be executed against your primary database.

If you run into a bug or have feedback, create a GitHub issue [here](https://github.com/prisma/extension-read-replicas/issues/new).

## Configure multiple database replicas

The `replicas` property accepts an array of `PrismaClient` instances for all your database replicas:

```ts
import { readReplicas } from '@prisma/extension-read-replicas'
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from './generated/prisma/client'

// Create main client
const mainAdapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL!,
})
const mainClient = new PrismaClient({ adapter: mainAdapter })

// Create multiple replica clients
const replicaAdapter1 = new PrismaPg({
  connectionString: process.env.DATABASE_URL_REPLICA_1!,
})
const replicaClient1 = new PrismaClient({ adapter: replicaAdapter1 })

const replicaAdapter2 = new PrismaPg({
  connectionString: process.env.DATABASE_URL_REPLICA_2!,
})
const replicaClient2 = new PrismaClient({ adapter: replicaAdapter2 })

// Configure multiple replicas
const prisma = mainClient.$extends(
  readReplicas({
    replicas: [replicaClient1, replicaClient2],
  })
)
```

If you have more than one read replica configured, a database replica will be randomly selected to execute your query.

## Executing read operations against your primary database

You can use the `$primary()` method to explicitly execute a read operation against your primary database:

```ts
const posts = await prisma.$primary().post.findMany()
```

## Executing operations against a database replica

You can use the `$replica()` method to explicitly execute your query against a replica instead of your primary database:

```ts
const result = await prisma.$replica().user.findFirst(...)
```
